<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<title>SlingOnG</title>
</head>
<body>
<h3>SlingOnG</h3>
<p><h4>About</h4>
The SlingOnG is a transaction manager (an implementation of Spring's PlatformTransactionManager SPI 
(Service Provider Interface) for the platform of <a href="https://sites.google.com/site/slim3appengine/slim3-datastore"
>Slim3 Datastore</a> &amp; Spring on GAE/J.<br />
<br />
In order for web app on GAE/J to assure strong data consistency through requests, as the AppEngine's <a href="https://developers.google.com/appengine/docs/java/datastore/structuring_for_strong_consistency"
>"Structuring Data for Strong Consistency"</a> page states, it must be done by the transaction.<br />
Slim3's Datastore supports global transaction over multiple entity groups (although GAE/J's Datastore 
now supports transaction over upto 5 entity groups but historically only one) and supports various 
relationships between entities upto many-to-many bidirectional relationship. Such flexibilities what Slim3 
Datastore provides onto GAE/J can bring safe feeling to developer's mind even for the case of unplanned 
future extension of data model of web app. <br />
Spring's transaction manager can release developer from cumbersome of managing transaction. <br />
Hence, hoping that SlingOnG's <a href="apidocs/com/newmainsoftech/spray/slingong/datastore/Slim3PlatformTransactionManager.html"
><code>Slim3PlatformTransactionManger</code></a> bridging Spring's transaction manager and 
Slim3 Datastore can ease some degree in your coding web app on GAE/J platform.
</p>
<p><h4>Usage guide</h4>
Slim3's <code>Datastore.beginTransaction</code> method and <code>GlobalTransaction.commit</code> method are 
automatically executed at beginning and end of each transaction by SlingOnG's 
<code>Slim3PlatformTransactionManger</code> as Spring Transaction support, thereby what needs to be 
basically done in your code is:
<ol>
	<li>Annotate method with the <code>@Transactional</code> annotation of Spring Transaction.
	</li>
	<li>In the code flow started by the method annotated with the <code>@Transactional</code> annotation:
		<ol>
			<li>Get current Slim3's <code>GlobalTransaction</code> object via <a href="https://slim3.googlecode.com/svn/trunk/slim3/javadoc/org/slim3/datastore/DatastoreDelegate.html#getCurrentGlobalTransaction%28%29"
				><code>DatastoreDelegate.getCurrentGlobalTransaction</code></a> method (or <a href="https://slim3.googlecode.com/svn/trunk/slim3/javadoc/org/slim3/datastore/Datastore.html#getCurrentGlobalTransaction%28%29"
				><code>Datastore.getCurrentGlobalTransaction</code></a> method.)
			</li>
			<li>Perform data model operation(s) such as put, delete, and/or query on 
				the <code>GlobalTransaction</code> object.
			</li>
		</ol>
	</li>
</ol>
Note: The next tip at the <a href="https://sites.google.com/site/slim3appengine/slim3-datastore/transactions/uses-for-transactions"
>"Uses For Transactions" page</a> in Slim3 web site is still valid even with SlingOnG:
<blockquote>
	<i>"<b>Tip</b>: <u>A transaction should happen as quickly as possible</u> to reduce the likelihood that 
	the entities used by the transaction will change, requiring the transaction be retried. As much as 
	possible, prepare data outside of the transaction, then execute the transaction to perform datastore 
	operations that depend on a consistent state. The application should prepare keys for objects used 
	inside the transaction, then fetch the entities inside the transaction."</i>
</blockquote>
Regarding rollback, Slim3's Datastore automatically performs it when it's properly configured as described 
at the <a href="https://sites.google.com/site/slim3appengine/slim3-datastore/installation"
>Slim3 Datastore installation instructions</a> page. And <code>Slim3PlatformTransactionManger</code> 
avoids duplicate rollback execution by gracefully discarding it.
</p>
<p><h4>Configuration guide</h4>
<ol>
	<li>First Of all, the <b>issue about Spring's proxing on GAE/J</b>.<br />
		In order to use Spring's transaction support on GAE/J, Spring Transaction must be configured via 
		rather AspectJ than Spring AOP because, in simple words, Spring Transaction is basically built 
		upon around-advise AOP and Spring proxy does not work on GAE/J (For more info about it, please 
		refer to <a href="https://gaeworkout.appspot.com/">gaeworkout.appspot.com</a>.) And how to 
		correctly configure Spring to use AspectJ for instantiating bean with injecting dependency too 
		requires the solid knowledge of Spring and AspectJ. Because of that, many folks believed that 
		Spring Transaction had not worked on GAE/J (without hack). (In this page, the only how-to for 
		configuring Slim3PlatformTransactionManger is provided (briefly, not in depth), and please be 
		advised that, for your own custom aspect (other than SlingOnG), you may encounter problem even 
		you configure the same kind way to define bean for your custom aspect due to something like what 
		in your classpath, AspectJ's aspectpath, whether your aspect needs to have dependency injected, 
		other factors like configuration for Spring's annotation support for related beans, and of 
		course Spring version.)
	</li>
	<li><b>Add dependency libraries</b> to your AppEngine web app project<br />
		Add the library binaries of Slim3, SlingOnG, and Spring as well as AppEngine SDK ones. For list of dependency 
		library, see <a href="dependencies.html">Dependencies page</a>.
		<ul>
			<li>To download SlingOnG
				<ul>
					<li>When you use auto-fashion build framework like Maven and others, see <a href="dependency-info.html"
						>Dependency Information page</a>.<br />
						For released version, the artifact will be able to be downloaded from Maven central 
						repository.<br />
						For snapshot build, use Sonatype's Nexus snapshots repo:
						<blockquote>
							<code>
								&lt;id&gt;sonatype-nexus-snapshots&lt;/id&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;
								&lt;name&gt;Sonatype Nexus Snapshots&lt;/name&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;
								&lt;url&gt;https://oss.sonatype.org/content/repositories/snapshots&lt;/url&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;
								&lt;releases&gt;&lt;enabled&gt;false&lt;/enabled&gt;&lt;/releases&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;
								&lt;snapshots&gt;&lt;enabled&gt;true&lt;/enabled&gt;&lt;/snapshots&gt;<br />
								&lt;/repository&gt;
							</code>
						</blockquote>
					</li>
					<li>For manual download, the SlingOnG artifact can be downloaded from <a href="https://oss.sonatype.org/content/groups/public/com/newmainsoftech/"
						>Sonatype's Nexus public repo</a>
					</li>
				</ul>
			</li>
			<li>To download Slim3
				<ul>
					<li>For Maven, Slim3 artifacts can be downloaded from the Seasar Foundation repo.
						<blockquote>
							<code>
								&lt;repository&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;name&gt;Seasar Foundation repo&lt;/name&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;id&gt;maven.seasar.org&lt;/id&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;url&gt;https://www.seasar.org/maven/maven2&lt;/url&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;snapshots&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;enabled&gt;true&lt;/enabled&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;/snapshots&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;releases&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
								&lt;updatePolicy&gt;never&lt;/updatePolicy&gt;<br />
								&nbsp;&nbsp;&nbsp;&nbsp;&lt;/releases&gt;<br />
								&lt;/repository&gt;<br />
							</code>
						</blockquote>
					</li>
					<li>For manual download, the Slim3 artifact can be downloaded from <a href="https://code.google.com/p/slim3/downloads/list"
						>Slim3 Google code site</a>.
					</li>
				</ul>
			</li>
			<li>To download Spring components
				<ul>
					<li>Refer to the <a href="http://blog.springsource.org/2009/12/02/obtaining-spring-3-artifacts-with-maven/"
						>"Obtaining Spring 3 Artifacts with Maven"</a> springsource blog post by Mr. Keith Donald.
					</li>
					<li>For manual download, you may use the following sites. (For the difference, 
						please follow the link of the above blog post.):
						<ul>
							<li><a href="https://repository.apache.org/index.html#welcome"
								>Maven central repo site</a>
							</li>
							<li><a href="http://ebr.springsource.com/repository/app/"
								>springsource EBR repo site</a>
							</li>
						</ul>
					</li>
				</ul>
			</li>
		</ul>
	</li>
	<li><b>Configuration for Slim3's Datastore library</b><br />
		<ul>
			<li>Follows the <a href="https://sites.google.com/site/slim3appengine/slim3-datastore/installation"
				>Slim3 Datastore installation instructions</a> in the Slim3's web site.
			</li>
			<li>If the project of your AppEngine's web app is a Maven project, then 
				org.codehaus.mojo:build-helper-maven-plugin and org.codehaus.mojo:apt-maven-plugin plugins 
				(and org.slim3:slim3-gen artifact dependency of course) must be configured for annotation 
				processing for Slim3 Datastore.<br />
				You may refer to <a href="https://code.google.com/p/spray/source/browse/trunk/slingong_test/pom.xml"
				>pom.xml of SlingOnG_test module</a> as an example though the execution phases of those 
				plugins have been set to the test phase because the SlingOnG_test module is the module just 
				for testing SlingOnG module. 
			</li>
		</ul>
	</li>
	<li><b>Add spring-aspects.jar and slingong.jar to AspectJ's aspectpath</b>.
	</li>
	<li>Configuration in <b>Spring's application context</b> .xml file<br />
		You may take a look of <a href="https://code.google.com/p/spray/source/browse/trunk/slingong_test/src/test/resources/com/newmainsoftech/spray/slingong/testContext2.xml"
		><code>testContext2.xml</code></a> as an example (although it is 
		for JUnit test with Spring's <code>@ContextConfiguration</code> annotation use.)
		<ul>
			<li>Add <code>&lt;<b>context:annotation-config</b> /&gt;</code> and <code>&lt;<b>context:component-scan</b> 
				<b>base-package</b>=&quot;<i>package_of_your_component</i>..*&quot; /&gt;</code>.<br />
				Replace the <i>package_of_your_component</i> part with actual package name of your 
				component.<br />
				(You may take a look at <a href="http://swik.net/Spring/Interface21+Team+Blog/Spring+2.5%27s+Comprehensive+Annotation+Support/b1z6v"
				>Spring 2.5's Comprehensive Annotation Support</a> SWiK blog post by Mr. Juergen Hoeller if you 
				need more information on the <code>context</code> tag, although it was written at Spring 
				ver 2.5 time.)
			</li>
			<li>Define a bean of <code>AnnotationBeanConfigurerAspect</code> aspect.
				<blockquote>
					<code>
						&lt;<b>bean</b>&nbsp;id=&quot;annotationBeanConfigurerAspect&quot;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						<b>class</b>=&quot;org.springframework.beans.factory.aspectj.<b>AnnotationBeanConfigurerAspect</b>&quot;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						<b>factory-method=&quot;aspectOf&quot;</b> /&gt;
					</code>
				</blockquote>
			</li>
			<li>Define a bean of <code>Slim3PlatformTransactionManager</code> class.
				<blockquote>
					<code>
						&lt;<b>bean</b>&nbsp;id=&quot;txManager&quot;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						<b>class</b>=&quot;com.newmainsoftech.spray.slingong.datastore.<b>Slim3PlatformTransactionManager</b>&quot; /&gt;
					</code>
				</blockquote>
			</li>
			<li>Define a bean of <code>AnnotationTransactionAspect</code> aspect with injecting 
				<code>Slim3PlatformTransactionManager</code> bean defined at the previous step.				
				<blockquote>
					<code>
						&lt;<b>bean</b>&nbsp;id=&quot;annotationTransactionAspect&quot; <br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						<b>class</b>=&quot;org.springframework.transaction.aspectj.<b>AnnotationTransactionAspect</b>&quot;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						<b>factory-method=&quot;aspectOf&quot;</b>&gt;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						&lt;<b>property</b> 
							&nbsp;<b>name=&quot;transactionManager&quot;</b>
							&nbsp;<b>ref=&quot;txManager&quot;</b> /&gt;<br />
						&lt;/bean&gt;
					</code>
				</blockquote>
			</li>
			<li>Define a bean of <code>AnnotationAwareAspectJAutoProxyCreator</code> class with 
				the dependencies of beans defined above steps:
				<blockquote>
					<code>
						&lt;<b>bean</b> <br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						class=&quot;org.springframework.aop.aspectj.annotation.<b>AnnotationAwareAspectJAutoProxyCreator</b>&quot;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						<b>depends-on=&quot;annotationBeanConfigurerAspect,annotationTransactionAspect,annotationTransactionOnStaticMethodAspect</b>&quot;&gt;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						&lt;property name=&quot;includePatterns&quot;&gt;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
						&lt;list&gt;&lt;value&gt;nothing&lt;/value&gt;&lt;/list&gt;<br />
						&nbsp;&nbsp;&nbsp;&nbsp;
						&lt;/property&gt;<br />
						&lt;/bean&gt;
					</code>
				</blockquote>
				This bean is a dummy bean in order to just force early instantiations of the beans defined 
				in the previous steps above.
			</li>
		</ul>
	</li>
	<li>Compile and test.
	</li>
</ol>
</p>
</body>
</html>